Skip to content

Update the documentation to use parquet output#2607

Merged
erikvansebille merged 83 commits intoParcels-code:mainfrom
erikvansebille:update_parquet_docs
May 4, 2026
Merged

Update the documentation to use parquet output#2607
erikvansebille merged 83 commits intoParcels-code:mainfrom
erikvansebille:update_parquet_docs

Conversation

@erikvansebille
Copy link
Copy Markdown
Member

Description

This PR updates all the documentation and tutorial notebooks to parse the parquet output introduced in #2600, as tracked in #2582. It also updated the parcels.read_particlefile() to use polars, which scales better for large output files

Checklist

AI Disclosure

  • This PR contains AI-generated content.
    • I have tested any AI-generated content in my PR.
    • I take responsibility for any AI-generated content in my PR.
    • Describe how you used it (e.g., by pasting your prompt): Help with how to use polars

@erikvansebille erikvansebille mentioned this pull request May 1, 2026
5 tasks
Copy link
Copy Markdown
Contributor

@VeckoTheGecko VeckoTheGecko left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As part of review I've looked both at the code, as well as visually compared plots before and after.

I've gone through and pushed some edits which were quite straight-forward:

  • 1b35bf9 Fixing a notebook
  • d977c88e7

Now the docs builds are passing

Other than that, I have some small comments - nothing major.


Given we're now using Polars in the docs, the tests, and in the read_particlefile function - I think its easiest just for us to add it as a core dependency to Parcels. We could make it an optional dependency, but we don't really have the tooling for that in Parcels (and I don't think its worth adding the tooling in this case).

If we add as a core dependency:

  • Update pyproject.toml and pixi.toml (run-dependencies to = ">=1.31.0" and feature.minimum.dependencies to = "1.31.*")
  • Update recipe.yaml

I'm happy to make those updates.

Comment thread docs/getting_started/tutorial_quickstart.md Outdated
Comment thread docs/getting_started/tutorial_quickstart.md Outdated
Comment thread docs/getting_started/tutorial_quickstart.md Outdated
Comment thread src/parcels/_core/particlefile.py
Comment thread tests/utils.py
Comment on lines +164 to 166
assert isinstance(df["time"][0], (cftime.datetime, datetime)), (
"CF-time values in Parquet did not get properly decoded. Are the attributes correct?"
)
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This assert should be updated pending the discussion from the other comment on the read_particlefile function.

Copy link
Copy Markdown
Member Author

@erikvansebille erikvansebille May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a TODO in 0241c28 .

Comment thread docs/getting_started/tutorial_quickstart.md
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've gone through this - really nice update! I think its quite clear

Comment thread docs/user_guide/examples/tutorial_nemo.ipynb
Comment thread docs/user_guide/examples/tutorial_nestedgrids.ipynb
@erikvansebille erikvansebille merged commit 80d023d into Parcels-code:main May 4, 2026
16 checks passed
@github-project-automation github-project-automation Bot moved this from Backlog to Done in Parcels development May 4, 2026
@erikvansebille erikvansebille deleted the update_parquet_docs branch May 4, 2026 09:56
@VeckoTheGecko
Copy link
Copy Markdown
Contributor

Given we're now using Polars in the docs, the tests, and in the read_particlefile function - I think its easiest just for us to add it as a core dependency to Parcels. We could make it an optional dependency, but we don't really have the tooling for that in Parcels (and I don't think its worth adding the tooling in this case).

If we add as a core dependency:

  • Update pyproject.toml and pixi.toml (run-dependencies to = ">=1.31.0" and feature.minimum.dependencies to = "1.31.*")
  • Update recipe.yaml

I'm happy to make those updates.

Do you agree with this @erikvansebille ?

@erikvansebille
Copy link
Copy Markdown
Member Author

Yes sorry, missed that comment about the polars dependency, and merged too fast. Can you make these updates in a new PR?

@VeckoTheGecko
Copy link
Copy Markdown
Contributor

All good, can do :)

@VeckoTheGecko VeckoTheGecko mentioned this pull request May 4, 2026
1 task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

2 participants